From 91f0fcde968cf2141e649040782041589ee66a7d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 12 May 2020 01:02:07 -0400 Subject: [PATCH] docs: Rearrange the introduction some more Fine-tune some wording, and move the Custom Drawing example earlier. --- docs/reference/gtk/getting_started.xml.in | 122 +++++++++++----------- 1 file changed, 59 insertions(+), 63 deletions(-) diff --git a/docs/reference/gtk/getting_started.xml.in b/docs/reference/gtk/getting_started.xml.in index d8e638f6e1..dba22cf0de 100644 --- a/docs/reference/gtk/getting_started.xml.in +++ b/docs/reference/gtk/getting_started.xml.in @@ -9,7 +9,7 @@ widget toolkit. Each user interface created by GTK consists of widgets. This is implemented in C using GObject, an object-oriented framework for C. - Widgets are organized in a hierachy. The window widget is the main container. + Widgets are organized in a hierarchy. The window widget is the main container. The user interface is then built by adding buttons, drop-down menus, input fields, and other widgets to the window. If you are creating complex user interfaces it is recommended to @@ -77,7 +77,7 @@ For this example org.gtk.example is used. For choosing an identifier for your application, see this guide. - Lastly gtk_application_new() takes #GApplicationFlags as input for your + Lastly gtk_application_new() takes GApplicationFlags as input for your application, if your application would have special needs. @@ -112,14 +112,14 @@ here. - Finally the window size is set using gtk_window_set_default_sizei() + Finally the window size is set using gtk_window_set_default_size() and the window is then shown by GTK via gtk_widget_show(). - When you exit the window, by for example pressing the X, - the g_application_run() in the main loop returns with a number - which is saved inside an integer named "status". Afterwards, the + When you close the window, by for example pressing the X, the + g_application_run() call returns with a number which is saved inside + an integer variable named status. Afterwards, the GtkApplication object is freed from memory with g_object_unref(). - Finally the status integer is returned and the GTK application exits. + Finally the status integer is returned and the application exits. While the program is running, GTK is receiving events. These are typically input events caused by @@ -204,7 +204,7 @@ here. - The rest of the code in example-1.c is identical to example-0.c. Next + The rest of the code in example-1.c is identical to example-0.c. The next section will elaborate further on how to add several GtkWidgets to your GTK application. @@ -213,9 +213,8 @@ Packing When creating an application, you'll want to put more than one widget - inside a window. When you want to put more than one widget into a window, - it becomes important to control how each widget is positioned and sized. - This is where packing comes in. + inside a window. When you do so, it becomes important to control how each widget + is positioned and sized. This is where packing comes in. GTK comes with a large variety of layout containers whose purpose it is to control the layout of the child widgets that are @@ -245,16 +244,60 @@ +
+ Custom Drawing + + Many widgets, like buttons, do all their drawing themselves. You + just tell them the label you want to see, and they figure out what font + to use, draw the button outline and focus rectangle, etc. Sometimes, it + is necessary to do some custom drawing. In that case, a GtkDrawingArea + might be the right widget to use. It offers a canvas on which you can + draw by connecting to the ::draw signal. + + + The contents of a widget often need to be partially or fully redrawn, + e.g. when another window is moved and uncovers part of the widget, or + when the window containing it is resized. It is also possible to explicitly + cause part or all of the widget to be redrawn, by calling + gtk_widget_queue_draw() or its variants. GTK takes care of most of the + details by providing a ready-to-use cairo context to the ::draw signal + handler. + + The following example shows a ::draw signal handler. It is a bit + more complicated than the previous examples, since it also demonstrates + input event handling by means of event controllers. + + + + + + + + + + + Drawing in response to input + Create a new file with the following content named example-4.c. + MISSING XINCLUDE CONTENT + + + You can compile the program above with GCC using: + + gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4` + + +
+
Building user interfaces - When construcing a more complicated user interface, with dozens + When constructing a more complicated user interface, with dozens or hundreds of widgets, doing all the setup work in C code is cumbersome, and making changes becomes next to impossible. Thankfully, GTK supports the separation of user interface layout from your business logic, by using UI descriptions in an - XML format that can be parsed by the #GtkBuilder class. + XML format that can be parsed by the GtkBuilder class. Packing buttons with GtkBuilder @@ -333,8 +376,8 @@ application menus, settings, GtkHeaderBar, GtkStack, GtkSearchBar, GtkListBox, and more. - The full, buildable sources for these examples can be found - in the examples/ directory of the GTK source distribution, or + The full, buildable sources for these examples can be found in the + examples/ directory of the GTK source distribution, or online in the GTK git repository. You can build each example separately by using make with the Makefile.example file. For more information, see the README included in the @@ -887,10 +930,7 @@ example_app_window_init (ExampleAppWindow *win) The code to populate the sidebar with buttons for the words found in each file is a little too involved to go into here. But we'll - look at the code to add the gears menu. - - As expected by now, the gears menu is specified in a GtkBuilder - ui file. + look at the code to add a checkbutton for the new feature to the menu. MISSING XINCLUDE CONTENT @@ -1005,48 +1045,4 @@ example_app_window_init (ExampleAppWindow *win)
-
- Custom Drawing - - Many widgets, like buttons, do all their drawing themselves. You - just tell them the label you want to see, and they figure out what font - to use, draw the button outline and focus rectangle, etc. Sometimes, it - is necessary to do some custom drawing. In that case, a GtkDrawingArea - might be the right widget to use. It offers a canvas on which you can - draw by connecting to the ::draw signal. - - - The contents of a widget often need to be partially or fully redrawn, - e.g. when another window is moved and uncovers part of the widget, or - when the window containing it is resized. It is also possible to explicitly - cause part or all of the widget to be redrawn, by calling - gtk_widget_queue_draw() or its variants. GTK takes care of most of the - details by providing a ready-to-use cairo context to the ::draw signal - handler. - - The following example shows a ::draw signal handler. It is a bit - more complicated than the previous examples, since it also demonstrates - input event handling by means of event controllers. - - - - - - - - - - - Drawing in response to input - Create a new file with the following content named example-4.c. - MISSING XINCLUDE CONTENT - - - You can compile the program above with GCC using: - - gcc `pkg-config --cflags gtk4` -o example-4 example-4.c `pkg-config --libs gtk4` - - -
- -- 2.30.2